home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / help / DOC < prev    next >
Text File  |  1995-07-29  |  5KB  |  117 lines
  1.  
  2. The low-level scohelp api enables Motif applications to act as 
  3. scohelp "clients", allowing requests to be made of scohelp to 
  4. display specific topics.  Topics can be either
  5. "hard coded" using the actual topic name, or can be a "widget tree" name.
  6. "Widget tree" names are intended to be used by a higher level api
  7. for internal SCO use only; the direct user of the low-level api will 
  8. always use "hard coded" topic names.
  9.  
  10. The Imakefile file how the library and include file should be compiled.
  11.  
  12. Callable Scohelp api - client side - descriptions of using the routines:
  13.  
  14. #include "api.h"
  15.  
  16. 1)  HelpStatus HelpOpen(client_context, toplevel, bookdir,
  17.                 wait_cursor, error_handler)
  18.      XtPointer  *client_context;
  19.      Widget     toplevel;
  20.      char       *bookdir;
  21.      void       ((*wait_cursor)(Boolean));
  22.      void       ((*error_handler)(char *));
  23.  
  24. HelpOpen() performs all of the initialization required for the scohelp
  25. client.  
  26.  
  27. The address of client_context (a global pointer) is passed to HelpOpen() 
  28. to allow HelpOpen() to return a pointer that represents all the information
  29. that scohelp needs about that client.  The pointer that is returned by
  30. HelpOpen() in the client_context parameter is then subsequently used in
  31. all the HelpDisplay() calls and the HelpClose() call that the client makes.
  32.  
  33. Toplevel refers to the toplevel widget of the application - used only to
  34. get display information.  NOTE:  In previous versions of the api this
  35. actually needed to be an always present, realized widget (because it
  36. was used for communication).  This is no longer a requirement.
  37.  
  38. Bookdir is the name of the documentation book (not a full pathname, but it
  39. is the name of the directory in which the topics in the book reside),
  40. and provides a default book name for the client.  This default book name
  41. may be overridden in subsequent calls to HelpDisplay() (see below), but
  42. if all of the information to be displayed is from this book, then the
  43. application developer may provide the filename to HelpOpen() and
  44. not have to pass it into HelpDisplay(). 
  45.  
  46. The wait_cursor required argument points to a routine within the client
  47. application which is used for turning the wait cursor on and off.  The
  48. wait_cursor routine will be called and passed a TRUE value when the wait 
  49. cursor is to be turned on during HelpDisplay() and HelpClose() (below), and a 
  50. FALSE value when it is to be turned off.
  51.  
  52. The error_handler argument points to a routine responsible for displaying
  53. error messages in the client.  This routine will be called by the api with
  54. a single argument - the string that is to be displayed in the client's
  55. error dialog.  For example, if the exec of scohelp fails, the api notifies
  56. the user that help is unavailable by invoking the client's error handler
  57. with the appropriate string argument.
  58.  
  59.  
  60. 2)   HelpStatus HelpDisplay( client_context, bookdir, obj_type, entry)
  61.      XtPointer         client_context;
  62.      char              *bookdir;
  63.      HelpObject        obj_type;
  64.      char              *entry;
  65.  
  66. HelpDisplay() is used to make a topic display request of scohelp.
  67.  
  68. Client_context is the same global pointer used in HelpOpen() but this time 
  69. the pointer returned by HelpOpen is passed, not the address of the pointer.
  70. After having called HelpOpen(), this pointer now represents the initialized 
  71. scohelp client information.
  72.  
  73. Bookdir is optional here, depending on whether or not one was passed into 
  74. HelpOpen().  If a valid filename (anything but NULL) is passed here, the book 
  75. specified by that name will be opened for display.  Otherwise, the default 
  76. book passed into HelpOpen() will be used instead.  Note: if neither bookname 
  77. is valid, the api will indicate an error has occured.
  78.  
  79. Obj_type is of the type HelpObject and must be one of either helpTopic 
  80. helpWidget.  Use of either of these objects results in scohelp displaying
  81. a topic.  HelpWidget is for use with specifying a widget tree hierarchy 
  82. and helpTopic specifies that an actual "hard-coded" topic name is passed
  83. in the "entry" parameter.  Entry is passed in the usual null-terminated
  84. character string format.  The helpWidget object type is intended for use
  85. with a higher level api; client programs using this api directly
  86. should use the helpTopic object type with the entry parameter.
  87.  
  88.  
  89.  
  90. 3)   HelpStatus HelpClose(client_context)
  91.      XtPointer   client_context;
  92.  
  93. HelpClose() is called only when the client application wants scohelp to
  94. close all of its associated documents.  
  95.  
  96. Client_context is the same pointer returned in HelpOpen() and represents the 
  97. necessary scohelp client information for scohelp to close the current client
  98. scohelp session.
  99.  
  100.  
  101. HelpDefaults.ad
  102. ===============
  103.  
  104. This file defines messages used by the low-level help api.  It should be
  105. included in the resource file for each client application that uses
  106. the help api.  It can be copied in, or included in the resource file.
  107.  
  108.  
  109. Sample Documentation
  110. ====================
  111.  
  112. There are several html source files that provide a small amount of text
  113. that should indicate what context they were called from.  These files
  114. should be installed into a directory called api_book under /usr/lib/scohelp
  115. on the documentation server you are testing with (by default this is the
  116. local machine).  
  117.